home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / libraries / mui20dev.lha / MUI / Developer / Autodocs / MUI_Group.doc < prev    next >
Text File  |  1994-02-11  |  11KB  |  394 lines
  1. TABLE OF CONTENTS
  2.  
  3. Group.mui/Group.mui
  4. Group.mui/MUIA_Group_ActivePage
  5. Group.mui/MUIA_Group_Child
  6. Group.mui/MUIA_Group_Columns
  7. Group.mui/MUIA_Group_Horiz
  8. Group.mui/MUIA_Group_HorizSpacing
  9. Group.mui/MUIA_Group_PageMode
  10. Group.mui/MUIA_Group_Rows
  11. Group.mui/MUIA_Group_SameHeight
  12. Group.mui/MUIA_Group_SameSize
  13. Group.mui/MUIA_Group_SameWidth
  14. Group.mui/MUIA_Group_Spacing
  15. Group.mui/MUIA_Group_VertSpacing
  16. Group.mui/Group.mui
  17.  
  18.     Group class is responsible for the complete layout
  19.     of a MUI window. A group may contain any number of
  20.     child objects, maybe buttons, cycle gadgets or
  21.     even other groups.
  22.  
  23.     Some attributes of group class define how the children
  24.     of a group are layouted. You can e.g. tell your group
  25.     to place its children horizontally (in a row) or
  26.     vertically (in a column). Since every MUI object knows
  27.     about its minimum and maximum dimensions, group class
  28.     has everything it needs to do that job.
  29.  
  30.     More sophisticated layout is possible by assigning
  31.     different weights to objects in a group or by
  32.     making a group two-dimensional.
  33.  
  34.     Beneath the layout issues, a group object passes
  35.     attributes and methods through to all of its
  36.     children. Thus, you can talk and listen to any
  37.     child of a group by talking and listening to the
  38.     group itself.
  39. Group.mui/MUIA_Group_ActivePage
  40.  
  41.     NAME
  42.     MUIA_Group_ActivePage -- [ISG], LONG
  43.  
  44.     VERSION
  45.     Available since version 5 of "group.mui".
  46.  
  47.     FUNCTION
  48.     Set (or get) the active page of a page group.
  49.     Only this active page is displayed, all others
  50.     are hidden.
  51.  
  52.     The value may range from 0 (for the first child)
  53.     to numchilds-1 (for the last child). Children are
  54.     adressed in the order of creation:
  55.  
  56.     PageGroup,
  57.        Child, Page_0_Object,
  58.        Child, Page_1_Object,
  59.        Child, Page_2_Object,
  60.        Child, Page_3_Object,
  61.        End;
  62.  
  63.     Note: You may *never* supply an incorrect page value!
  64.  
  65.     SEE ALSO
  66.     MUIA_Group_PageMode
  67. Group.mui/MUIA_Group_Child
  68.  
  69.     NAME
  70.     MUIA_Group_Child -- [I..], Object *
  71.  
  72.     FUNCTION
  73.     You supply a pointer to a previously created MUI object
  74.     here. This object will be treated as child of the group,
  75.     the group is responsible for positioning the object.
  76.  
  77.     Of course you can specify any number of child objects,
  78.     limited only by available memory.
  79.  
  80.     Normally, the value for a MUIA_Group_Child tag is
  81.     a direct call to another MUI_NewObject(), childrens
  82.     are generated "on the fly".
  83.  
  84.     When a group is disposed, all of its childs will also
  85.     get deleted. If you supply a NULL pointer as child,
  86.     the group object will fail and previously dispose all
  87.     valid childs found in the taglist.
  88.  
  89.     This behaviour makes it possible to generate a complete
  90.     application within one single (but long) MUI_NewObject()
  91.     call. Error checking is not necessary since every error,
  92.     even if it occurs in a very deep nesting level, will
  93.     cause the complete call to fail without leaving back
  94.     any previously created object.
  95.  
  96.    EXAMPLES
  97.     Please have a look at some of the supplied example
  98.     programs.
  99.  
  100.    SEE ALSO
  101.     MUIA_Group_Horiz
  102. Group.mui/MUIA_Group_Columns
  103.  
  104.     NAME
  105.     MUIA_Group_Columns -- [IS.], LONG
  106.  
  107.     FUNCTION
  108.     Indicate number of columns in a two dimensional group.
  109.     If you use this tag, the total number of children must
  110.     be dividable by the number of columns.
  111.  
  112.     The children will be positioned in a two dimensional
  113.     array, e.g. allowing easy creation of button fields
  114.     (maybe for calculator).
  115.  
  116.     The children in your taglist are always read line 
  117.     by line.
  118.  
  119.     When MUI layouts two-dimensional groups, it does
  120.     actually two layout calculations, one for the rows
  121.     and one the columns. Parameters like weights and
  122.     dimensions are handled this way:
  123.  
  124.     - the minimum width of a column/row is the maximum
  125.       minimum width of all objects in this column/row.
  126.  
  127.     - the maximum width of a column/row is the minimum
  128.       maximum width of all objects in this column/row.
  129.  
  130.     - the weight of a column/row is the sum of all
  131.       objects in this column/row.
  132.  
  133.     Actually, there is no difference if you use
  134.     MUIA_Group_Columns or MUIA_Group_Rows.
  135.  
  136.     EXAMPLE
  137.  
  138.     /* group of labeled string gadgets */
  139.  
  140.     GroupObject,
  141.        MUIA_Group_Columns, 2,
  142.        MUIA_Group_Child  , label1,
  143.        MUIA_Group_Child  , string1,
  144.        MUIA_Group_Child  , label2,
  145.        MUIA_Group_Child  , string2,
  146.        MUIA_Group_Child  , label3,
  147.        MUIA_Group_Child  , string3,
  148.            ...
  149.        End;
  150.  
  151.     SEE ALSO
  152.     MUIA_Group_Rows, MUIA_Group_Horiz
  153. Group.mui/MUIA_Group_Horiz
  154.  
  155.     NAME
  156.     MUIA_Group_Horiz -- [I..], BOOL
  157.  
  158.     FUNCTION
  159.     Boolean value to indicate whether the objects in
  160.     this group shall be layouted horizontally or
  161.     vertically. Defaults to FALSE.
  162.  
  163.     This is the easy way of telling your group how
  164.     it has to look like. If you want two-dimensional
  165.     groups, you have to use MUIA_Group_Columns
  166.     or MUIA_Group_Rows.
  167.  
  168.     EXAMPLE
  169.     GroupObject,
  170.        MUIA_Group_Horiz, TRUE,
  171.        MUIA_Group_Child, obj1,
  172.        MUIA_Group_Child, obj2,
  173.        MUIA_Group_Child, obj3,
  174.        End;
  175.  
  176.     SEE ALSO
  177.     MUIA_Group_Columns, MUIA_Group_Rows, MUIA_Group_Child
  178. Group.mui/MUIA_Group_HorizSpacing
  179.  
  180.     NAME
  181.     MUIA_Group_HorizSpacing -- [IS.], LONG
  182.  
  183.     FUNCTION
  184.     Number of pixels to be inserted between horizontal
  185.     elements of a group.
  186.  
  187.     Please use this tag wisely, you will override the
  188.     user's prefered default setting!
  189.  
  190.     SEE ALSO
  191.     MUIA_Group_Spacing, MUIA_Group_VertSpacing
  192. Group.mui/MUIA_Group_PageMode
  193.  
  194.     NAME
  195.     MUIA_Group_PageMode -- [IS.], BOOL
  196.  
  197.     VERSION
  198.     Available since version 5 of "group.mui".
  199.  
  200.     FUNCTION
  201.     Settings this attribute to TRUE makes the current group a page
  202.     group. Page groups always display only one their childs, which
  203.     one can be adjusted with the MUIA_Group_ActivePage attribute.
  204.  
  205.     Imagine you have a preferences window with several different
  206.     pages, e.g. the MUI preferences with object, frame, image,
  207.     font, screen, keyboard and system prefs. Instead of one
  208.     separate window for each group, you could put all pages into
  209.     one page group and have a cycle gadget for page switching.
  210.     This will make your program easier to use since the user
  211.     won't have to handle a lot of windows. However, he will not
  212.     be able to work with more than one page at the same time.
  213.  
  214.     Sizes are calculated as follows:
  215.  
  216.     The minimum width/height of a page group is the maximum
  217.     minimum width/height of all its childs.
  218.  
  219.     The maximum width/height of a page group is the minimum
  220.     maximum width/height of all its childs.
  221.  
  222.     When the maximum width/height of a child in a page group is
  223.     smaller than the minimum width/height of the page group
  224.     (since it contains another child with big minimum width/height),
  225.     the child be centered.
  226.  
  227.     Page groups are not limited in depth, children of a page
  228.     group may of course be other page groups.
  229.  
  230.     If you want to have a gadget only visible under certain
  231.     conditions, you could make a page group containing this
  232.     gadget and an empty rectangle object.
  233.  
  234.     If you want TAB cycling for the objects in a page group,
  235.     simply include all objects in the cycle chain (as if
  236.     they all were visible at the same time).
  237.  
  238.     EXAMPLE
  239.     demo program "Pages.c"
  240.  
  241.     SEE ALSO
  242.     MUIA_Group_ActivePage
  243. Group.mui/MUIA_Group_Rows
  244.  
  245.     NAME
  246.     MUIA_Group_Rows -- [IS.], LONG
  247.  
  248.     FUNCTION
  249.     Indicate number of rows in a two dimensional group.
  250.     If you use this tag, the total number of children must
  251.     be dividable by the number of rows.
  252.  
  253.     The children will be positioned in a two dimensional
  254.     array, e.g. allowing easy creation of button fields
  255.     (maybe for calculator).
  256.  
  257.     The children in your taglist are always read line
  258.     by line.
  259.  
  260.     When MUI layouts two-dimensional groups, it does
  261.     actually two layout calculations, one for the rows
  262.     and one the columns. Parameters like weights and
  263.     dimensions are handled this way:
  264.  
  265.     - the minimum width of a column/row is the maximum
  266.       minimum width of all objects in this column/row.
  267.  
  268.     - the maximum width of a column/row is the minimum
  269.       maximum width of all objects in this column/row.
  270.  
  271.     - the weight of a column/row is the sum of all
  272.       objects in this column/row.
  273.  
  274.     Actually, there is no difference if you use
  275.     MUIA_Group_Columns or MUIA_Group_Rows.
  276.  
  277.     SEE ALSO
  278.     MUIA_Group_Columns, MUIA_Group_Horiz
  279. Group.mui/MUIA_Group_SameHeight
  280.  
  281.     NAME
  282.     MUIA_Group_SameHeight -- [I..], BOOL
  283.  
  284.     FUNCTION
  285.     Boolean value to indicate that all children of this
  286.     group shall have the same height.
  287.  
  288.     BUGS
  289.     Up to version 5 of groupclass, using MUIA_Group_SameHeight
  290.     could make objects larger than their maximum height. This
  291.     has been fixed for version 6.
  292.  
  293.     SEE ALSO
  294.     MUIA_Group_SameSize, MUIA_Group_SameWidth
  295. Group.mui/MUIA_Group_SameSize
  296.  
  297.     NAME
  298.     MUIA_Group_SameSize -- [I..], BOOL
  299.  
  300.     FUNCTION
  301.     This is a shorthand for MUIA_Group_SameWidth and
  302.     MUIA_Group_SameHeight, it sets both of these
  303.     attributes at once.
  304.  
  305.     Using MUIA_Group_SameSize, you won't need to think
  306.     if your group is horizontal or vertical, both
  307.     cases are handled automatically.
  308.  
  309.     Forcing all objects of a group to be the same size
  310.     is e.g. useful for a row of buttons. It's visually
  311.     more attractive when these buttons have equal sizes
  312.     instead of being just as big as the text within.
  313.  
  314.     BUGS
  315.     Up to version 5 of groupclass, using MUIA_Group_SameSize
  316.     could make objects larger than their maximum size. This
  317.     has been fixed for version 6.
  318.  
  319.     EXAMPLE
  320.  
  321.     /* three buttons, same size */
  322.  
  323.     GroupObject,
  324.        MUIA_Group_Horiz   , TRUE,
  325.        MUIA_Group_SameSize, TRUE,
  326.        MUIA_Group_Child   , but1,
  327.        MUIA_Group_Child   , but2,
  328.        MUIA_Group_Child   , but3,
  329.        End;
  330.  
  331.     SEE ALSO
  332.     MUIA_Group_SameWidth, MUIA_Group_SameHeight
  333. Group.mui/MUIA_Group_SameWidth
  334.  
  335.     NAME
  336.     MUIA_Group_SameWidth -- [I..], BOOL
  337.  
  338.     FUNCTION
  339.     Boolean value to indicate that all children of this
  340.     group shall have the same width.
  341.  
  342.     BUGS
  343.     Up to version 5 of groupclass, using MUIA_Group_SameWidth
  344.     could make objects larger than their maximum width. This
  345.     has been fixed for version 6.
  346.  
  347.     SEE ALSO
  348.     MUIA_Group_SameSize, MUIA_Group_SameHeight
  349. Group.mui/MUIA_Group_Spacing
  350.  
  351.     NAME
  352.     MUIA_Group_Spacing -- [IS.], LONG
  353.  
  354.     FUNCTION
  355.     This is a shorthand for MUIA_Group_HorizSpacing and
  356.     MUIA_Group_VertSpacing, it sets both of these
  357.     attributes at once.
  358.  
  359.     Using MUIA_Group_Spacing, you won't need to think
  360.     if your group is horizontal or vertical, both
  361.     cases are handled automatically.
  362.  
  363.     Note that setting a spacing value for a group
  364.     overrides the user's default settings. Please
  365.     use it only if you have a good reason.
  366.  
  367.     EXAMPLE
  368.  
  369.     /* no space between obj1 and obj2: */
  370.  
  371.     GroupObject,
  372.        MUIA_Group_Horiz  , TRUE,
  373.        MUIA_Group_Spacing, 0,
  374.        MUIA_Group_Child  , obj1,
  375.        MUIA_Group_Child  , obj2,
  376.        End;
  377.  
  378.     SEE ALSO
  379.     MUIA_Group_HorizSpacing, MUIA_Group_VertSpacing
  380. Group.mui/MUIA_Group_VertSpacing
  381.  
  382.     NAME
  383.     MUIA_Group_VertSpacing -- [IS.], LONG
  384.  
  385.     FUNCTION
  386.     Number of pixels to be inserted between vertical
  387.     elements of a group.
  388.  
  389.     Please use this tag wisely, you will override the
  390.     user's prefered default setting!
  391.  
  392.     SEE ALSO
  393.     MUIA_Group_Spacing, MUIA_Group_HorizSpacing
  394.